【小ネタ】SSMドキュメントをCloudFormation運用する際は “UpdateMethod: NewVersion” を付けたい

AWS Systems Manager(SSM)ドキュメント をCloudFormationテンプレートとして 作成、運用していく際にハマったことを備忘録として残します。 結論はタイトルのとおりです。

UpdateMethod パラメータについて

これは AWS::SSM::Document の1パラメータです。 Replace (デフォルト)もしくは NewVersion のいずれかの値となります。

• Replace: 指定したドキュメントが既に存在する場合、既存のドキュメントを置き換えます
• NewVersion: 指定したドキュメントが既に存在する場合、新しいバージョンを作成します

UpdateMethod パラメータを付けていない場合

"UpdateMethod: NewVersion" を指定していない場合の挙動は Replace になります。

試しに以下テンプレートを展開して、挙動を確かめてみます。

AWSTemplateFormatVersion: '2010-09-09'
Resources:
  HelloWorldDoc:
    Type: AWS::SSM::Document
    Properties:
      Content:
        schemaVersion: '2.2'
        mainSteps:
        - action: aws:runShellScript
          name: runCommands
          inputs:
            timeoutSeconds: '60'
            runCommand:
            - 'echo Hello World'
      DocumentFormat: YAML
      DocumentType: Command
      Name: Custom-HelloWorld
      # UpdateMethod: NewVersion

展開後にテンプレートを修正して、スタックを更新します。

AWSTemplateFormatVersion: '2010-09-09'
Resources:
  HelloWorldDoc:
    Type: AWS::SSM::Document
    Properties:
      Content:
        schemaVersion: '2.2'
        mainSteps:
        - action: aws:runShellScript
          name: runCommands
          inputs:
            timeoutSeconds: '60'
            runCommand:
            - 'echo Hello World(v2)'
      DocumentFormat: YAML
      DocumentType: Command
      Name: Custom-HelloWorld
      # UpdateMethod: NewVersion

すると以下のようなエラーが出て、正常に更新できませんでした。

CloudFormation cannot update a stack when a custom-named resource requires replacing. Rename Custom-HelloWorld and update the stack again.

"UpdateMethod: Replace"の場合、 更新したい際は「一度スタックを削除する」か、「ドキュメント名を変更する」かの対応となります。 少し不便です。

"UpdateMethod: NewVersion" を付けた場合

前のスタックは削除して、 "UpdateMethod: NewVersion" を付けたテンプレートを展開します。

AWSTemplateFormatVersion: '2010-09-09'
Resources:
  HelloWorldDoc:
    Type: AWS::SSM::Document
    Properties:
      Content:
        schemaVersion: '2.2'
        mainSteps:
        - action: aws:runShellScript
          name: runCommands
          inputs:
            timeoutSeconds: '60'
            runCommand:
            - 'echo Hello World'
      DocumentFormat: YAML
      DocumentType: Command
      Name: Custom-HelloWorld
      UpdateMethod: NewVersion

同じように、テンプレートを修正して、スタックを更新します。

AWSTemplateFormatVersion: '2010-09-09'
Resources:
  HelloWorldDoc:
    Type: AWS::SSM::Document
    Properties:
      Content:
        schemaVersion: '2.2'
        mainSteps:
        - action: aws:runShellScript
          name: runCommands
          inputs:
            timeoutSeconds: '60'
            runCommand:
            - 'echo Hello World(v2)'
      DocumentFormat: YAML
      DocumentType: Command
      Name: Custom-HelloWorld
      UpdateMethod: NewVersion

無事更新できました。

SSMドキュメントを見てみると、ドキュメントの新規バージョン 2 が作成されていますね。

おわりに

以上、SSMドキュメントのUpdateMethodパラメータ挙動を確かめてみました。

SSMドキュメントをCFnテンプレートで管理していく際は、 NewVersion を指定したいですね。 また、このドキュメントを利用する側(SSM State Manager など) では、 バージョン指定を LATEST にしておくと良さそうです。

参考

• AWS::SSM::Document - AWS CloudFormation